MultipleResponseItemOptions

Description

MultipleResponseItemOptions holds the Options type, as well as an enumeration to determine if a service should stop on failure and send an error message or continue processing. It also enables you to limit the data that is returned in a response.

Parameters

Name	Type	Description
options	Extension. See Options.	Options extension base. Holds a name value pairing for future elements.
multiOption	MultipleOption	Enumeration element that holds the option to continue processing or stop when an error is encountered.
sections	SectionsOption	Enumeration element that controls the sections of an item that should be returned.
specifiedSections	string	If SECTIONS-SPECIFIED is used in the sections element above, enter the specified section or sections here. The available options are described below in the Usage section.
limitedField	FieldIdentifier	Enables you to limit the return results based on one or more fields that you identify.

Usage

The MultipleResponseItemOptions contains the same functionality as MultipleOptions, but it also enables you to limit the return results based on item sections or specific fields that you identify.

You use the following parameters to control service handling and the amount of data that is returned in the response:

multiOption – Use the multiOption element to specify whether the service should continue if an error is encountered, or stop and return an error. If any failures occur, each successive error message is appended to the string that is returned. Multiple error messages are separated by a single newline. If you specify CONTINUE-ON-FAILURE, then failures do not result in a return before all items have been processed. For more information, see MultipleOption.
sections and specifiedSections – Use these elements to specify which parts of an item should be returned in order to limit the data that is returned for a given item. The sections that are not specified are not included in the response. For example, if the items have a large number of item links, notes, URL and file attachments that don't need to be returned in the response, use these parameters to return only the sections of an item you want. For more information, see SectionsOption.
In the sections parameter, specify one of the following enumeration options:
- SECTIONS-ALL – Returns all sections. This is the default value for the sections argument. If no value is specified, ALL is the assumed value.
- SECTIONS-NONE – No sections are returned (only the ItemIdentifier is returned). Note that the ItemIdentifier is always returned, regardless of the value or values specified in the sections parameter.
- SECTIONS-SPECIFIED – Returns sections that you specify.
You can use a comma-separated list in specifiedSections to return only the sections of an item you want. For example:
```
<urn:specifiedSections>SECTION:FIXED,SECTION:EXTENDED</urn:specifiedSections>
```
This ensures that only the fixed and extended sections of an item are returned. Here are some of the possible sections you can specify:
- SECTION:FIXED – All parameters in TTItem (from <urn:itemType> to <urn:url>) prior to the extendedField parameter are returned.
- SECTION:EXTENDED – Returns all of the extendedFields in TTItem.
- SECTION:ATTACHMENTS – Returns all of the attachment sections of TTItem. You can return the next four sections simply by specifying:
```
<urn:specifiedSections>SECTION:ATTACHMENTS</urn:specifiedSections>
```
- SECTION:NOTES – Returns all note sections of TTItem.
- SECTION:ITEMLINKS – Returns all itemLink sections of TTItem.
- SECTION:URLATTACHMENTS – Returns all urlAttachment sections of TTItem.
- SECTION:FILEATTACHMENTS – Returns all fileAttachment sections of TTItem.
Note: If you specify SECTION:NONE after other sections, those preceding sections will not be returned. For example, SECTION:FIXED,SECTION:NONE,SECTION:EXTENDED will only return the extendedField sections.
limitedField – Use the limitedField element to use specific fields to limit the item data that is returned. For example, you can specify one or more fields to limit a service response to return only the fields that you want to return. In the event that limitedField contradicts the sections value, the sections specification takes precedence. The following XML shows how to limit return results using the limitedField option.
```
<urn:limitedField>
    <urn:displayName>Severity</urn:displayName>
    <urn:id>69</urn:id>
    <urn:uuid>f4eff572-2e29-4d7f-8478-8e9e16865c2c</urn:uuid>
    <urn:dbName>SEVERITY</urn:dbName>
</urn:limitedField>
```

XML

The following XML shows MultipleResponseItemOptions in the <urn:options> element of a typical call.

<urn:options>
    <urn:extraOption>
        <urn:name></urn:name>
        <urn:value></urn:value>
    </urn:extraOption>
    <urn:multiOption>CONTINUE-ON-FAILURE</urn:multiOption>
    <urn:sections>SECTIONS-SPECIFIED</urn:sections>
    <urn:specifiedSections>SECTION:EXTENDED</urn:specifiedSections>
    </urn:limitedField>
</urn:options>